Skip to main content

Hosted Checkout Pages and Payment Linkage Overview

Purpose​

Hosted checkout pages provide a flexible payment gateway experience by allowing users to create templates. These templates serve as reusable layouts and configurations for checkout pages, supporting multiple payment types and linking to individual payment transactions. This ensures a streamlined and secure payment process.

Structure and Relationships​

Checkout Page Template (Template Level)​

  • A Checkout Page Template defines the layout and configuration for generating specific checkout pages.
  • The template associates with various payment types, making it reusable for different transactions with unique amounts and currency configurations.
  • One Template → Many Checkout Pages: Multiple checkout pages can be generated from a single template, each with unique transaction details like amount and currency.

Checkout Page (Instance Level)​

  • Each Checkout Page is created from a template and represents a specific payment instance, holding unique transaction details.
  • Each page can only be associated with one successful payment, ensuring transaction accuracy and finality.
  • A Checkout Page can have multiple payment attempts in an "initiated" state, but only one of them will eventually complete successfully.

Payment Flow Linkage​

  • Each checkout page links to payments, which begin in an "initiated" state. These transactions are associated with specific payment types (e.g., card, QR code, bank transfer).
  • The first payment transaction that completes successfully is permanently linked to the checkout page. Subsequent attempts remain in other states without affecting the "successful" status.

Key Rules​

  • Single Success Rule: Each checkout page can have multiple initiated payments, but only one of these payments can reach a successful state. This helps maintain transaction integrity by ensuring each checkout page links to just one completed transaction.
  • Dynamic Payment Initialization: Before a payment is created, certain interactions (e.g., fetching an ID from a partner for QR payments) may be necessary. This enables the checkout page to dynamically prepare and render required elements like a QR code.

Workflow for Creating and Linking Hosted Checkout Pages and Payments​

1. Template Creation​

  • Step: Define a checkout page template, specifying layout, payment types, and organization details.
  • Outcome: The template is saved and can be reused for creating multiple checkout pages.

2. Checkout Page Creation from Template​

  • Step: Generate a checkout page from the template for a specific transaction, including amount and currency details.
  • Outcome: A checkout page is created, initialized with linked payment types, ready to accept payments.

3. Initiate Payment Process​

  • Step: When the user accesses the checkout page, available payment types are presented. Each type can initiate a transaction, starting with a status of “initiated.”
  • Outcome: The page presents payment options (e.g., card, bank transfer, QR code) with the ability for the user to select their preferred method.

4. Complete Payment​

  • Step: The user completes a payment transaction. If successful, the payment status updates to “completed.”
  • Outcome: The checkout page links to this successful payment, while any other initiated payments remain in their respective states.

5. Update Status​

  • Step: Once the payment is processed, the page updates its overall status based on the outcome (completed, failed, etc.).
  • Outcome: Only one payment per checkout page will reflect a “successful” state; all other payments stay as initiated or failed, ensuring transactional accuracy.

Use Case Example with QR Code Payment​

  1. Template Setup: An organization sets up a checkout page template with QR code as a payment type.
  2. Checkout Page Creation: A specific checkout page is generated from this template for a transaction with an amount and currency.
  3. ID Fetching: Before creating the actual payment, a backend process contacts the QR code payment provider to fetch the unique QR ID or data required for display.
  4. Display: The QR code data is displayed on the checkout page for the user to scan and pay.
  5. Transaction Completion: Upon successful QR code scan and payment confirmation, the payment is marked as completed, linking it to the checkout page.

State Transition Diagram​

This file outlines the workflow and relationships between checkout page templates, checkout pages, and payment linkage, ensuring a secure and efficient payment gateway process.